home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / listings / v_01_02 / clune.exe / DOS_FUNC.TXT < prev    next >
Text File  |  1989-11-27  |  5KB  |  101 lines
  1.  
  2. DOCUMENTATION OF DOS_FUNC.C
  3.  
  4. Documentation dated, 6/89, updated 11/89.
  5. Program and documentation Copyright (c) 1989, E.R.I.  All rights reserved.
  6.  
  7. INTRODUCTION
  8.      DOS_FUNC.C is my source file to support PC-DOS software interrupts or
  9. functions that were built up from PC-DOS interrupts.
  10.  
  11. DOS_FUNC.C EXTERNALLY-VISIBLE FUNCTIONS
  12.      The externally-visible functions of DOS_FUNC.C are declared in DOS_FUNC.H.
  13. You may #include that file to declare these functions.
  14.  
  15. FUNCTION: count_files()
  16. TYPE: int
  17. ARGUMENTS: one character string
  18.  
  19.      count_files(filespec) counts the number of files that match the filespec
  20. template, which follows the standard DOS conventions.  For example,
  21. i=count_files("*.*"); would return the     total number of files in the default
  22. directory.  It is useful for dynamically allocating string pointers for the
  23. get_dir() function below (q.v.).  See my WDIR.C for an example of this kind
  24. of program usage.
  25.  
  26.  
  27. FUNCTION: del_fhandle()
  28. TYPE: int
  29. ARGUMENTS: one character string
  30.  
  31.      del_fhandle(filespec) deletes all files that conform to the filespec
  32. template, which follows standard DOS conventions.  Thus,
  33. del_fhandle("A:\FOO\*.C"); would delete all files with the extension ".C" from
  34. the A: drive subdirectory FOO.  The function returns a flag value 1 if a file
  35. could not be deleted, 0 if file(s) were deleted or no matching files were found.
  36.  
  37.  
  38.  
  39. FUNCTION: disk_space()
  40. TYPE: long int
  41. ARGUMENTS: one int
  42.  
  43.      disk_space(drive) returns the number of bytes available on the disk
  44. specified by drive.  drive is a flag variable with the following significance: 0
  45. means the default drive, 1 means drive A:, 2 means B:, etc.  This function was
  46. written to deal with a very unpleasant bug in the ITEX library function,
  47. saveim().  That function will tell you that an image file was successfully
  48. written, even if there was insufficient disk space to write the file.  That is,
  49. saveim() will only tell you whether an image file write was INITIATED
  50. sucessfully, not whether it was completed properly.  You should always verify
  51. that there is sufficient space on a disk before writing an image.  If you like,
  52. you can use safe_save() for that purpose (see FILEMAIN.C for details).
  53.  
  54.  
  55. FUNCTION: fget_time_date()
  56. TYPE: void
  57. ARGUMENTS: two character strings
  58.  
  59.      fget_time_date(filespec,timedate); gets the time and date of creation
  60. (or last change) of the filespec file, and writes it into the timedate
  61. string. The format is: MM-DD-YY HH:MM.SS, where MM is month, DD is day, 
  62. YY is year, HH is hour, MM is minutes, and SS is seconds.  The timedate
  63. string length is <= 18 characters (only minutes and seconds are filled
  64. out to two characters if they are less than 10).  If the filespec file
  65. does not exist, timedate returns all 0s.  I use fget_time_date() to make
  66. sure that the image file associated with a scotoma map has not changed.
  67. That is, if a new file is created using the same file name, the time
  68. and date will be different, so I will be able to detect the error and
  69. not map a scotoma onto the wrong image.
  70.  
  71.  
  72. FUNCTION: fname_unused()
  73. TYPE: int
  74. ARGUMENTS: one character string
  75.  
  76.      fname_unused(filespec) determines whether a file already exists that uses
  77. the name and path specified by filespec. This is useful for avoiding mistakenly
  78. creating a file that has the same name as an existing file, which automatically
  79. deletes the previous file under DOS.  I use this function in all my file writes
  80. (including safe_save() in FILEMAIN.C). fname_unused() returns 0 if the file
  81. already exists, 1 otherwise.
  82.  
  83.  
  84.  
  85. FUNCTION: get_dir()
  86. TYPE: int
  87. ARGUMENTS: one character string, one pointer to an array of strings, and one
  88. int.
  89.  
  90.      i=get_dir(filespec, fnames, max_files) gets a directory of files that 
  91. conform to the FILESPEC template, and writes their names into the FNAMES array.
  92. MAX_FILES is the size of the FNAMES array: this routine will not generate more
  93. than MAX_FILES file names.  This routine is used in the get_file() function of
  94. menu.c. NOTE WELL: get_dir() malloc()s space for the FNAMES pointers, depending
  95. on the actual length of the file names. IT DOES NOT free() that space after 
  96. usage. You must free() the space malloc()ed by get_dir() when you are through
  97. using the FNAMES strings. WARNING: make sure to free() only the space that was
  98. actually malloc()ed. That is, if you allow for 100 pointers and get_dir() only
  99. uses 20, only free() FNAMES[0] to FNAMES[19]. get_dir() returns the number of
  100. strings actually used: use that value to determine how many strings to free().
  101.